The REDCAMEL Approach for Designing APIs

Learn about the REDCAMEL mnemonic device and how to tackle any design problems.

Introduction#

Designing an API for a service is a complex task, and no universal algorithm exists to model an optimal API for a system. It requires thorough analysis and understanding of the users’ requirements and the workflow of the overall system. Identifying the requirements allows us to make different design decisions, such as architectural styles, data formats, protocols and their versions, and so on. In this course, we devise an approach called REDCAMEL that governs the design of an API for a service.

svg viewer
Evaluation and Latency budget
API Model
Design Considerations
REquirements
EL
AM
DC
RE
REDCAMEL
The REDCAMEL acronym

We’re going to use the REDCAMEL approach in the coming chapters as we design various APIs. We’ll expand on the REDCAMEL approach in the following sections.

Requirements (RE)#

In the requirements lessons, we identify the functional and non-functional requirements of the API to be designed. This helps us identify the functionalities we need to address while designing an API. Further, we also mention the prerequisite concepts a learner would need to know before designing an API. The structure of the requirements lesson contains the following sections:

  • Introduction or motivation: This section briefly defines the problem and its motivation.

  • Functional requirements: In this section, we identify the essential API functional requirements that we’ll focus on in the API model phase.

  • Non-functional requirements: Here, we focus on the non-functional requirements crucial for our API to work smoothly.

  • Prerequisites: In this section, we list the concepts learners should understand before moving toward the design of API.

  • Chapter structure: Here, we give an overview of the lessons in the rest of the chapter.

The following illustration demonstrates the section we focus on in the requirements lesson:

Chapter structure
Prerequisites
Non-functional requirements
Functional requirements
Introduction or motivation
Requirements
The lesson structure for the requirements

Design considerations (DC)#

In the design considerations lessons, we make some technical decisions based on the services involved in a system and the client interaction with them. We mainly divide these lessons into the following sections:

  • Design overview and workflow: In this section, we give an overview and workflow of the system for which we aim to design an API.

  • API architecture styles: Here, we decide which architecture style to use between the client, API gateway, and back-end servers.

  • Data formats: This section focuses on the data formats to use for exchanging data between different entities. For example, we decide between JSON, XML, binary, or any other data type.

  • Protocols and their versions: Here, we opt for suitable protocols and their versions that suit our requirements and needs for data communication between clients and servers.

The structure of the design consideration lessons is shown in the following figure:

Protocol and its version
Data formats
API architecture styles
Design overview and workflow
Design considerations
Structure of the design considerations lessons

API model (AM)#

In the API model lessons, we define multiple endpoints to perform various operations to meet functional requirements. Following our decisions in the design consideration phase, we present each operation's request and response structure by accessing the endpoint corresponding to each operation. We exchange data between the client and server in the formats we decide on in the design consideration phase.

Overall, we have the following sections in the lesson on the API model:

  • Base URL and API endpoints: Here, we define the base URL for our API and related endpoints for each service. We also present essential data entities that can be a part of the request, response, or both.

  • Data entities: This section highlights the data elements required for a particular design problem.

  • The request-response format of each operation: This section focuses on each operation's request and response format.

  • Failed requests statuses: At the end of the lesson, we present failed request status codes that can occur if any request processing fails.

The structure of the API model lessons is depicted below:

Failed requests statuses
The request-response format of each operation
Data entities
Base URL and API endpoints
API model
Structure of the API model lessons

Evaluation and latency budget (EL)#

We divide the final lesson of each design problem into two major sections: evaluation of the non-functional requirements and latency budget.

  • Evaluation of non-functional requirements: In this first section, we describe the techniques we chose to meet the non-functional requirements of the API, such as scalability, availability, low latency, security, and so on.

  • Latency budget: In this section, we estimate the latency of our API in light of the numbers we derived in the lesson on back-of-the-envelope calculations. The estimated latency is then used to calculate the final response time of an API.

The structure of the evaluation and latency budget lessons is shown below:

Latency budget and response time of the API
Achieving non-functional requirements
Evaluation and latency budget
Structure of the evaluation and latency budget lessons

Discussion on Response Time

Conventions for the Design Chapters of the Course